<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--

  @(#)package.html

-->
</head>
<body bgcolor="white">

<p>
This package models the spread of a worm in a network using a macroscopic 
epidemic model. Since the epidemic may encompass hundreds of thousands of 
hosts, the idea is to partially decouple the worm spread from the packet-level 
network model. Thus, we model the "whole Internet" at a coarse macroscopic 
level (for the worm spread) and some part of it in more detail (the 
"microscopic" or network level) using SSFNet entities such as routers and 
hosts. This is illustrated in <a href="#Figure 1">Figure 1</a>.
</p><p>
<a name="Figure 1"><img SRC="doc-files/abstraction_levels.png"><br><br>
<i>Figure 1: Mixed abstraction level model.</i></a>
</p><p>
The rationale behind this mixed abstraction level model and the benefits and 
trade-offs involved are described in the paper 
<a href="#mascots paper">[Liljenstam et al., 2002]</a>.
</p>

<h2>Package Specification</h2>

<p>
Version 0.5.1 supports the following features:
<ul>
  <li>Deterministic or stochastic epidemic models (time stepped). 
      Models assume a worm spreading by uniform random scanning, such as 
      the Code Red v2 worm or the Sapphire/Slammer worm.
    <ul>
      <li><i>Deterministic</i> model based on well known differential equation 
          system ("general epidemic model" or "SIR-model") derived from 
	  result by Kermack-McKendrick. </li>
      <li><i>Stochastic</i> model based on similar assumptions. </li>
    </ul>
  </li>
  <li>Homogeneous or stratified population models: <br>
      <ul>
        <li><i>Homogeneous:</i> All susceptible hosts in the Internet form a 
               homogeneous 'population'.</li>
	<li><i>Stratified:</i> 'Population' of susceptible hosts is stratified 
               by AS, i.e. each AS represents a sub-population.</li>
      </ul>
  <li>Initialization choices for stratified epidemic model:<br>
      <ul>
        <li><i>'Uniform':</i> Uniform distribution of susceptibles over leaf 
            ASes and uniform infection rate between ASes.</li>
	<li><i>'Code Red':</i> Distribution of susceptibles based on empirical 
            data for Code Red worm. Infection rates based on announced IP 
            space distribution (from empirical data).</li>
      </ul>
  </li>
  <li>Simple worm scan traffic model:<br>
      Models egress scans going through border router(s).
      <ul>
        <li><i>'Mean rate':</i> Scanning traffic modeled by simple mean scan 
	    rate flow model. (Piecewise constant flow.)</li>
      </ul>
  </li>

  <li>DML configurable<br>
    <ul>
      <li>Parameters such as
      <ul>
        <li>Total susceptible population (<i>s_0</i>)</li>
        <li>Initially infected population (<i>i_0</i>)</li>
	<li>Infection parameter (<i>beta</i>)</li>
      </ul></li>
      <li>Implementation choices for
      <ul>
        <li>Epidemic model (deterministic/stochastic)</li>
        <li>Initializer code for epidemic</li>
        <li>Removal function for epidemic</li>
      </ul></li>
    </ul>
  </li>
  <li>Example model of a campus network with vulnerable machines operating 
      during the Code Red v2 attack.
  </li>
  <li>Regression tests.</li>
</ul>
</p><p>
Planned features for future releases include:
<ul>
  <li>Extended scan traffic models.</li>
  <li>Connectivity feedback.</li>
  <li>Parallel execution support.</li>
</ul>
</p><p>
Please see <a href="#mascots paper">[Liljenstam et al., 2002]</a> for more 
details on the models and assumptions.
</p><p>
The link between the network and epidemic models is provided by two 
pseudo-protocol-sessions: 
<tt><a href="WormProtocolSession.html">WormProtocolSession</a></tt> and 
<tt><a href="GatewayProtocolSession.html">GatewayProtocolSession</a></tt>. 
The first instance created of these sessions will 
create the global epidemic model entity and a timer object to drive it 
forward. Hence, every model that uses the worm package <i>must</i> include at 
least one instance of either <tt>WormProtocolSession</tt> or 
<tt>GatewayProtocolSession</tt>.
</p><p>
All <tt>WormProtocolSession</tt> instances will register with the 
epidemic model to signal that they each represent a <i>vulnerable host</i>. 
As the infection progresses the epidemic model will pick hosts at random 
for infection and may thus pick hosts that are modeled at the network level. 
When this happens it will call the method 
<tt>WormProtocolSession.becomeInfected()</tt> which is an empty 
placeholder for events to happen when a host has become infected.
Of course, the network level may also contain any number of hosts that are not 
vulnerable to the worm. By not running the <tt>WormProtocolSession</tt>, the 
host is not mapped to the macroscopic level and will never be picked for 
infection.
</p><p>
Instances of the <tt>GatewayProtocolSession</tt> also register at the 
macroscopic level. If the scan traffic model is configured (an thus invoked), 
then these registered gateways received information on the worm scan traffic 
rate hitting the router. This can be used for instance to inject packets at 
the network level or model router stress. Note that traffic modeling only 
makes sense for a <i>stratified</i> macroscopic model.
</p><p>
In a <i>homogeneous</i> model this mapping of network-level hosts to the 
macroscopic level is quite straight forward; all hosts are mapped into a 
big 'cloud' at the macroscopic level. More interesting is the case of a 
stratified model (and in this model we stratify by AS). In this case network 
entities (hosts and routers) belonging to a certain AS at the network level 
is mapped to the corresponding AS at the macroscopic level, as illustrated in 
<a href="#Figure 2">Figure 2</a>. Here <tt>Net</tt> attributes that represent 
AS boundaries are required to contain the <tt>ASN</tt> attribute, where the 
user specifies the real AS number that this network should be mapped to at 
the macroscopic level. Hence, hosts and routers belonging to this <tt>Net</tt> 
will map to the AS given by the <tt>ASN</tt> at the macroscopic level. 
Note that there will effectively be one interdomain level topology at the 
network level and one interdomain level topology at the macroscopic level. 
<b>Also note</b> that there is currently no check if these topologies are 
consistent or make any sense with respect to each other.
</p><p>
<a name="Figure 2"><img SRC="doc-files/mapping.png"><br><br>
<i>Figure 2: Mapping between abstraction levels.</i></a>
</p><p>
See the <a href="MacroscopicModelConfigurator.html#configGlobalOptions(com.renesys.raceway.DML.Configuration, com.renesys.raceway.DML.Configuration)"><tt>configGlobalOptions()</tt> method of <tt>MacroscopicModelConfigurator</tt></a> (and 
<a href="#examples">examples</a>) for more information on how to configure the 
parameters for the macroscopic model, both epidemic and traffic.
<p>
<h3>Installation:</h3>
Unpack the package tar-ball in the <tt>ssfnet</tt> (root) directory. Then 
refer to package <tt>README</tt> file for instructions on compiling the 
package, generating javadoc, and running 'validation' tests.
</p>
<p>
<a name="examples"><h3>Examples:</h3></a>
We start with a simple example to describe the overall capabilities of the 
package. Then we proceed with smaller examples to demonstrate the DML 
configuration options. All of the examples described here are in the 
<tt>test</tt> subdirectory and many of them are used as regression tests for 
the package.
<h4>Campus Network Under Attack</h4>
This first example provided here requires a system with Perl and gnuplot 
installed. <br><br>
Go to the <tt>test</tt> subdirectory. 
<br>
The perl-script <tt>campusTestPlot.pl</tt> will run the 
<tt>campusUnderAttack.dml</tt>, and extract data on host infections from the 
debug output and plot the results using gnuplot. The scenario is the exact 
same network as the <tt>campus2.dml</tt> network in the 
<tt>littleComboDemo</tt> SSFNet example, with the difference that all hosts 
(clients and servers) are vulnerable to the worm. How the DML is configured 
will be described in more detail later on. Suffice it to say here that 
the changes made to the <tt>campus2.dml</tt>  to achieve this are minimal:
<ol>
  <li>The <tt>WormProtocolSession</tt> has been added to the hosts' protocol 
      stacks.</li>
  <li>The parameters of the macroscopic model are configured at the top-most 
      level <tt>Net</tt> in the <tt><b>worm_model</b></tt> attribute.</li>
</ol>
</p><p>
The example (approximately) models the spread of the Code Red v2 worm and 
infections occurring on the campus network.
</p><p>
The resulting graph should look like <a href="#Figure 3">Figure 3</a>.
</p><p>
<a name="Figure 3"><img SRC="doc-files/campusUnderAttack_example.png"><br><br>
<i>Figure 3: Example graph: CampusUnderAttack scenario. 
Shows global infection spread (number of hosts infected in the whole 
Internet), and time-points for local infections in the studied campus 
network</i></a>
</p>
<h4>Single Vulnerable Host (Deterministic Model)</h4>
<p>
For a minimal example in the same vein, see 
<tt><a href="doc-files/singleHost.dml">singleHost.dml</a></tt> which 
models a single home user during an ongoing worm attack (parameters for 
Code Red v2). In this example the network model does nothing except start 
up the epidemic and wait for something to happen. If the epidemic runs long 
enough, the user's host will eventually become infected.
</p><p>
The relevant DML sections are shown below in <a href="#Figure 4">Figure 4</a>.
The macroscopic level is configured using the global <tt>worm_model</tt> 
attribute. Inside it we set the parameters for the epidemic model in the 
<tt>Epidemic</tt> attribute, and switch on debug output. The single 
host modeled on the network level runs the <tt>WormProtocolSession</tt> 
to signal that it is vulnerable to the worm.
<br><br>
<a name="Figure 4">
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" NOSAVE >
  <tr bgcolor="#ffffff" nosave>
    <td nosave><font face="Arial,Helvetica" size=-1><font color="#777777">
Net&nbsp;[<br>
&nbsp;&nbsp;frequency 1000000000<br>
&nbsp;&nbsp;AS_status boundary<br>
&nbsp;&nbsp;ospf_area 0<br>
<br></font><font color="#000000">
&nbsp;&nbsp;worm_model [<br>
&nbsp;&nbsp;&nbsp;&nbsp;Epidemic [<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s_0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;359999&nbsp;&nbsp;&nbsp;#&nbsp;number of susceptible hosts (initially) =N-1<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;i_0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;# number of infected hosts (initially)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;beta&nbsp;&nbsp;1.235e-9&nbsp;&nbsp;&nbsp;# infection parameter =(1.6/3600)/N<br>
&nbsp;&nbsp;&nbsp;&nbsp;]<br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;debug true<br>
&nbsp;&nbsp;]<br></font><font color="#777777">
<br>
...
<br><br></font><font color="#000000">
&nbsp;&nbsp;clientGraph [graph [<br>
&nbsp;&nbsp;&nbsp;&nbsp;ProtocolSession [<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name WormProtocolSession<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;use SSF.App.Worm.WormProtocolSession<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;debug true<br>
&nbsp;&nbsp;&nbsp;&nbsp;]<br></font><font color="#777777">
&nbsp;&nbsp;&nbsp;&nbsp;ProtocolSession [name ip use SSF.OS.IP]<br>
&nbsp;&nbsp;]<br>
]
</font></font>
    </td>
  </tr>
</table>
<p>
<i>Figure 4: DML for minimal example with a single vulnerable host at the 
network level (microscopic level). This host is one of 359,999 vulnerable 
hosts in the whole Internet, and the scenario starts with a single infected 
host somewhere in the Internet. By default a deterministic epidemic model 
is used (system of differential equations) and a homogeneous population.
</i></a>
</p><p>
The infection will show up in the debug output (as shown in this 
<a href="doc-files/ex_singleHost.out">output clip</a>), 
but otherwise will have no effect on the model, since no action is coded 
into the the host.
</p>
<h4>Stochastic Epidemic Model</h4>
<p>
This same scenario can also be modeled using a stochastic epidemic model. 
In DML 
(<a href="doc-files/singleHostStoch.dml"><tt>singleHostStoch.dml</tt></a>) 
this is done by replacing the default implementation of the epidemic 
model with another class, as shown below.
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" NOSAVE >
  <tr bgcolor="#ffffff" nosave>
    <td nosave><font face="Arial,Helvetica" size=-1><font color="#777777">
&nbsp;&nbsp;worm_model [<br>
&nbsp;&nbsp;&nbsp;&nbsp;Epidemic [<br></font><font color="#000000">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;use SSF.App.Worm.StochasticWormEpidemic<br><font color="#777777">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s_0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;359999&nbsp;&nbsp;&nbsp;#&nbsp;number of susceptible hosts (initially) =N-1<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;i_0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;# number of infected hosts (initially)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;beta&nbsp;&nbsp;1.235e-9&nbsp;&nbsp;&nbsp;# infection parameter =(1.6/3600)/N<br>
&nbsp;&nbsp;&nbsp;&nbsp;]<br>
</font></font>
    </td>
  </tr>
</table>
<p>
We can compare the evolution of the epidemic in the two models (deterministic 
and stochastic) as in the semi-log plot in <a href="#Figure 5">Figure 5</a>.
</p>
<a name="Figure 5"><img SRC="doc-files/singleHost_comp.png"><br><br>
<i>Figure 5: Example comparison between epidemic evolutions for a 
deterministic and a stochastic model. (Semi-log plot.) As the population of 
infected grows, the stochastic model settles down to the mean growth rate 
predicted by the deterministic model.
</i></a>
</p><p>
Note that the epidemic grows until all vulnerable hosts are infected (unlike 
the campus example, where the epidemic decreased towards the end. That is, 
the campus example also modeled removals of infected hosts as observed during 
the Code Red v2 event. The DML clip below illustrates how this is done in 
<tt>campusUnderAttack.dml</tt> by substituting the implementation class 
for the 'gamma function' used to compute removals.
</p>
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" NOSAVE >
  <tr bgcolor="#ffffff" nosave>
    <td nosave><font face="Arial,Helvetica" size=-1><font color="#777777">
&nbsp;&nbsp;worm_model [<br>
&nbsp;&nbsp;&nbsp;&nbsp;Epidemic [<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s_0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;359999&nbsp;&nbsp;&nbsp;# number of susceptible hosts (initially) =N-1<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;i_0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;# number of infected hosts (initially)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;beta&nbsp;&nbsp;1.235e-9&nbsp;&nbsp;&nbsp;# infection parameter =(1.6/3600)/N<br>
<br></font><font color="#000000">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;gamma_function SSF.App.Worm.CodeRedGammaFunction<br></font><font color="#777777">
&nbsp;&nbsp;&nbsp;&nbsp;]<br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;debug true<br>
&nbsp;&nbsp;]<br>
</font></font>
    </td>
  </tr>
</table>

<h4>A Simple Stratified Model</h4>
<p>
One can study worm propagation in different parts of the network (the 
Internet) using a stratified model. The package supports stratification by 
AS, i.e. each AS forms a subpopulation. The 
(<a href="doc-files/twoASsingleHosts.dml"><tt>twoASsingleHosts.dml</tt></a>) 
example depicts a simple scenario with two ASes modeled at the network level 
(microscopic level). AS one contains a single vulnerable host (at the network 
level). 
The DML clip below illustrates how a stratified model is switched on through 
the <tt>stratified_on</tt> attributed and an inter-domain topology graph 
is loaded using the <tt>as_graph</tt> attribute.
When using a stratified model it is also important to set the initial 
values for the subpopulations in the epidemic model, i.e. the inital fraction 
of susceptibles and infected assigned to different strata (ASes). The class 
to use for initialization is set through the <tt>initializer</tt> attribute. 
This example uses the <tt>SSF.App.Worm.CodeRedWormEpidemicInitializer</tt> 
to initialize based on an empirical distribution derived from Code Red II data.
Lastly, the <tt>AS_num</tt> attribute of the AS boundary <tt>Net</tt>:s must 
be set to choose which AS to map to at the macroscopic level.
</p>
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" NOSAVE >
  <tr bgcolor="#ffffff" nosave>
    <td nosave><font face="Arial,Helvetica" size=-1><font color="#777777">
&nbsp;&nbsp;worm_model [<br></font><font color="#000000">
&nbsp;&nbsp;&nbsp;&nbsp;stratified_on&nbsp;&nbsp;true&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;# stratified model (by AS)<br>
&nbsp;&nbsp;&nbsp;&nbsp;as_graph&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ex_as_topology.adj&nbsp;&nbsp;# AS level topology file (adjacencies)<br>
<br></font><font color="#777777">
&nbsp;&nbsp;&nbsp;&nbsp;Epidemic [<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s_0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;359999&nbsp;&nbsp;&nbsp;# number of susceptible hosts (initially) =N-1<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;i_0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;# number of infected hosts (initially)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;beta&nbsp;&nbsp;1.235e-9&nbsp;&nbsp;&nbsp;# infection parameter =(1.6/3600)/N<br>
<br></font><font color="#000000">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;initializer SSF.App.Worm.CodeRedWormEpidemicInitializer<br>
&nbsp;&nbsp;&nbsp;&nbsp;]<br></font><font color="#777777">
<br>
&nbsp;&nbsp;&nbsp;&nbsp;debug true<br>
&nbsp;&nbsp;]<br>
<br>
&nbsp;&nbsp;Net [ id 0<br>
&nbsp;&nbsp;&nbsp;&nbsp;AS_status boundary<br></font><font color="#000000">
&nbsp;&nbsp;&nbsp;&nbsp;AS_num 557 # ASN 557, just some AS with outdegree one in the adjacency file<br></font><font color="#777777">
&nbsp;&nbsp;&nbsp;&nbsp;ospf_area 0<br>
...
</font></font>
    </td>
  </tr>
</table>

<h4>Worm Scan Traffic</h4>
<p>
The package also includes a very simple model of worm scan traffic as it 
passes through egress border routers. It models the mean rate of scan packets 
as a piecewise constant flow through the router. The mean scan rate is 
proportional to the number of scanning hosts inside the AS, i.e. the number of 
infected hosts in the AS. The 
(<a href="doc-files/twoAStraffic.dml"><tt>twoAStraffic.dml</tt></a>) 
example uses the same two AS scenario, but using initializer code that assigns 
70% of all susceptibles to one of the ASes, and the remaining 30% to the other 
AS. Thus, all susceptibles are assigned to the two ASes that are modeled at 
the network level. (It also uses the CRv2 based removal function.)
The DML clip below illustrates how the traffic model is invoked using the 
<tt>Traffic</tt> attribute.
</p>
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" NOSAVE >
  <tr bgcolor="#ffffff" nosave>
    <td nosave><font face="Arial,Helvetica" size=-1><font color="#777777">
&nbsp;&nbsp;worm_model [
&nbsp;&nbsp;&nbsp;&nbsp;stratified_on&nbsp;&nbsp;true&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;# stratified model (by AS)<br>
&nbsp;&nbsp;&nbsp;&nbsp;as_graph&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ex_as_topology.adj&nbsp;&nbsp;# AS level topology file (adjacencies)<br>
<br></font><font color="#777777">
&nbsp;&nbsp;&nbsp;&nbsp;Epidemic [<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s_0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;359999&nbsp;&nbsp;&nbsp;# number of susceptible hosts (initially) =N-1<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;i_0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;# number of infected hosts (initially)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;beta&nbsp;&nbsp;1.235e-9&nbsp;&nbsp;&nbsp;# infection parameter =(1.6/3600)/N<br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;initializer SSF.App.Worm.test.TestWormEpidemicInitializer<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;gamma_function SSF.App.Worm.CodeRedGammaFunction # removal process<br>
&nbsp;&nbsp;&nbsp;&nbsp;]<br></font><font color="#000000">
&nbsp;&nbsp;&nbsp;&nbsp;Traffic [<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;use SSF.App.Worm.MeanRateWormTraffic<br>
&nbsp;&nbsp;&nbsp;&nbsp;]<br></font><font color="#777777">
<br>
&nbsp;&nbsp;&nbsp;&nbsp;debug true<br>
&nbsp;&nbsp;]<br>
<br></font><font color="#000000">
...
</font></font>
    </td>
  </tr>
</table>
</p>
<p>
<a href="#Figure 6">Figure 6</a> shows the resulting scan traffic rates at the 
two gateway routers together with the global epidemic progression. Since the 
egress scan rate is proportional to the number of infected hosts inside the 
AS, the difference in rates will correspond to the fraction of susceptibles 
assigned to each AS.
</p>
<a name="Figure 6"><img SRC="doc-files/twoAStraffic.png"><br><br>
<i>Figure 6: Example of scan traffic through gateways at two different ASes.
</i></a>
</p>

<h3>Revision History</h3>

<table>
  <tr>
    <td valign="top"><b>v 0.5.1</b></td><td valign="top">:</td>
    <td>Bugfixes:<br>
          <li>Infection parameters for stratified model.</li>
	  <li>Triggering of infections at network level.</li>
	  <li>Calculation of infections in deterministic stratified model.</li>
	  <li>Subpopulation bounds in stratified model.</li>
	  <li>Makefile, IPSpaceDistr and CR2SuscFracDistr targets missing</li> 
    </td>
    <td valign="top"><b>v 0.5</b></td><td valign="top">:</td>
    <td>Complete redesign. More flexible (DML configurable), and 
        extensible.<br>
	Added:
	  <li>Stratified population</li>
	  <li>Flexible initializers - Code Red II initializer example</li>
	  <li>Flexible removal fctn - Code Red v2 removals</li>
	  <li>Simple scan traffic model - mean rate example</li>
	  <li>Regression tests and more examples</li>
	  <li>Stochastic model</li>
	  <li>RNG seeding based on global SSFNet seed</li>
    </td>
  </tr><tr>
    <td><b>v 0.4</b></td><td>:</td>
    <td>First external release.</td>
  </tr>
</table>
</p>

<h3>Design Notes</h3>
<p>
The package design makes heavy use of the <i>strategy</i> pattern 
<a href="#gamma et al">[Gamma et al., 2000]</a> to allow substitution of 
algorithms, implementations and initialization code and hence also make the 
models extensible. Thus, the core class <tt>MacroscopicModel</tt> defers 
implementations of submodels to abstract base classes <tt>WormEpidemic</tt> 
and <tt>WormTraffic</tt>. Subclasses of these provide specific 
models/implementations, such as <tt>DeterministicWormEpidemic</tt> and 
<tt>MeanRateWormTraffic</tt> respectively. Moreover, the <tt>WormEpidemic</tt> 
model defers initialization of the model state to the 
<tt>WormEpidemicInitializer</tt> class, another abstract base class. Thus, 
it's possible to substitute in some other initalization code to change the 
distributions generating the initial state of the model. Similarly, 
<tt>GammaFunction</tt> is an abstract base class for functions used to 
compute removals in the deterministic epidemic model.
</p><p>
The choice of implementations can thus be done through DML configuration, 
avoiding recompilation similarly to other aspects of SSFNet.
</p>

<h3>Regression Tests</h3>

The tests supplied in the <tt>test</tt> subdirectory do the following:
<table>
  <tr>
    <td valign="top"><tt><b>single_host<b></tt></td>
    <td>Models single vulnerable host at the microscopic level and a 
        homogeneous population of 359,000 susceptible hosts at the macroscopic 
	level. Used the <i>deterministic</i> epidemic model to model a worm 
	infection that starts from a single host and spreads throughout the 
	population. At some point the host at the microscopic level is 
	infected. <br>
	Tests the spread dynamics of the deterministic model in a homogeneous 
	population.
    </td>
  </tr><tr>
    <td valign="top"><tt><b>two_as_traffic<b></tt></td>
    <td>Similar to <tt>single_host</tt> test, but uses the <i>stochastic</i> 
        model for the epidemic. <br>
	Tests the spread dynamics of the stochastic model in a homogeneous 
	population.
  </tr><tr>
    <td valign="top"><tt><b>two_as_single_host<b></tt></td>
    <td>Models a stratified population (broken down per AS) with all 
        susceptibles allocated to two specific ASes (that each contain a 
	single vulnerable host modeled at the microscopic level).
	Otherwise similar to <tt>single_host</tt> test.<br>
	Tests the spread dynamics of a stratified population.
    </td>
  </tr><tr>
    <td valign="top"><tt><b>two_as_traffic<b></tt></td>
    <td>Simple model of egress scan traffic from two ASes. Otherwise similar 
        to <tt>two_as_single_host</tt>. <br>
	Tests that the traffic observed from the 'mean rate egress scan 
        traffic' model is as expected.
    </td>
  </tr>
</table>

<h2>Related Documentation</h2>

<b>References</b>
<ul>
  <li><a name="mascots paper">
<a href="http://www.cs.dartmouth.edu/~mili/publs_by_area.html#Worms">
<b>A Mixed Abstraction Level Simulation Model of Large-Scale Internet Worm Infestations,</b><br>
Michael Liljenstam, Yougu Yuan, BJ Premore, David Nicol,<br>
in Proceedings of the Tenth IEEE/ACM Symposium on Modeling, Analysis and Simulation of Computer and Telecommunication Systems (MASCOTS), IEEE Computer Society Press, Fort Worth, TX, Oct 2002.
</a></a></li>
  <li><a name="gamma et al">
<b>Design Patterns: Elements of Reusable Object-Oriented Software,</b><br>
Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides,<br>
Addison-Wesley Professional Computing Series, New York, 1995.
</a></li>
</ul>

</b>For more information, please see:</b>
<ul>
  <li><a href="http://www.cs.dartmouth.edu/~mili/research/ssf/worm/index.html">
Contributed package home page</a></li>
  <li><a href="http://www.cs.dartmouth.edu/~mili/research/worms/index.html">
Author's page on worms and worm modeling</a></li>
</ul>

<!-- Put @see and @since tags down here. -->


<h3>Author</h3>
<tt>SSF.App.Worm</tt> has been written and is maintained by 
<a href="http://www.cs.dartmouth.edu/~mili">Michael Liljenstam, ISTS, 
Dartmouth College</a> 
<tt><a href="mailto:mili@ists.dartmouth.edu">&lt;mili@ists.dartmouth.edu&gt;</a></tt>.


<!-- $Id: package.html,v 1.8 2003/03/18 17:03:31 mili Exp mili $ -->

</body>
</html>
